
###############################################################################
#
#  EGSnrc BEAMnrc graphical user interface: help messages
#  Copyright (C) 2015 National Research Council Canada
#
#  This file is part of EGSnrc.
#
#  EGSnrc is free software: you can redistribute it and/or modify it under
#  the terms of the GNU Affero General Public License as published by the
#  Free Software Foundation, either version 3 of the License, or (at your
#  option) any later version.
#
#  EGSnrc is distributed in the hope that it will be useful, but WITHOUT ANY
#  WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
#  FOR A PARTICULAR PURPOSE.  See the GNU Affero General Public License for
#  more details.
#
#  You should have received a copy of the GNU Affero General Public License
#  along with EGSnrc. If not, see <http://www.gnu.org/licenses/>.
#
###############################################################################
#
#  Author:          Joanne Treurniet, 1998
#
#  Contributors:    Blake Walters
#                   Dave Rogers
#                   Iwan Kawrakow
#
###############################################################################
#
#  The contributors named above are only those who could be identified from
#  this file's revision history.
#
#  This code is part of the BEAMnrc code system for Monte Carlo simulation of
#  radiotherapy treatments units. BEAM was originally developed at the
#  National Research Council of Canada as part of the OMEGA collaborative
#  research project with the University of Wisconsin, and was originally
#  described in:
#
#  BEAM: A Monte Carlo code to simulate radiotherapy treatment units,
#  DWO Rogers, BA Faddegon, GX Ding, C-M Ma, J Wei and TR Mackie,
#  Medical Physics 22, 503-524 (1995).
#
#  BEAM User Manual
#  DWO Rogers, C-M Ma, B Walters, GX Ding, D Sheikh-Bagheri and G Zhang,
#  NRC Report PIRS-509A (rev D)
#
#  As well as the authors of this paper and report, Joanne Treurniet of NRC
#  made significant contributions to the code system, in particular the GUIs
#  and EGS_Windows. Mark Holmes, Brian Geiser and Paul Reckwerdt of Wisconsin
#  played important roles in the overall OMEGA project within which the BEAM
#  code system was developed.
#
#  There have been major upgrades in the BEAM code starting in 2000 which
#  have been heavily supported by Iwan Kawrakow, most notably: the port to
#  EGSnrc, the inclusion of history-by-history statistics and the development
#  of the directional bremsstrahlung splitting variance reduction technique.
#
###############################################################################


proc help {i} {
    global help_text helvfont
    help_dialog .help "Help" $help_text($i) info 0 OK
}

proc help_srcopts { w iopt } {
    global source_text
    if { $iopt==10 || $iopt==12 || $iopt==13 } {
	set src_gif {}
    } else {
	set src_gif src$iopt
    }
    help_gif $w.help $source_text($iopt) $src_gif
}

proc help_nbrem { iopt w } {

    if {$iopt==1} {
      set text {
You have selected uniform bremsstrahlung splitting (UBS).

You must enter the number of bremsstrahlung photons produced after each\
        Bremstrahlung event (NBRSPL).  Each Bremsstrahlung photon has a weight\
        of the inverse of the number of photons produced.  \
        If you selected the Russian Roulette option "on for electrons, \
        higher order brem photons, annihilation photons", this number is also\
        equal to the annihilation photon splitting number.

Russian Roulette is used to optimize UBS and reduce CPU time by eliminating\
        most of the secondary charged particles generated by split photons. \
        Russian Roulette is implemented by choosing a random\
        number for each electron created by a split photon at the time\
        of interaction and comparing this number to a threshold of 1/NBRSPL.  \
        If the random number is less than the threshold, the electron\
        survives and has its weight increased by a factor of NBRSPL. \
        Otherwise, the electron is eliminated.  When Russian Roulette is on \
        then higher-order bremsstrahlung and annihilation photons created by \
        the surviving charged particles are also split.

If you are interested in the electrons at the bottom of the accelerator \
        you should run with Russian Roulette off (and with an increased \
        CPU time).

With Russian Roulette off, UBS can result in dose efficiencies up to \
        7 times greater than with no splitting.
      }
   } elseif {$iopt==2} {
      set text {
You have selected directional bremsstrahlung splitting (DBS).

You must enter the bremsstrahlung splitting number (NBRSPL) as well\
        as the radius of the splitting field and the SSD at which\
        this radius is defined.  The splitting radius should at least\
        enclose the entire treatment field and, preferably, should go\
        far enough beyond the its edges that \
        contribution to central axis dose from fat photons scattering \
        back from outside the splitting field is negligible.  We have \
        found that a splitting field radius of 10 cm sufficient \
        for 10x10 cm^2 fields in simulated 6 MV (SL25) and 18 MV (KD2) \
        beams.  Note that increasing the radius of the splitting field \
        will decrease the efficiency of DBS.

In standard DBS, very few charged particles reach the bottom of the\
        accelerator, and those that do are all high-weight ("fat"). \
        This is because, in an effort to reduce CPU time spent tracking \
        charged particles, DBS only allows interactions that could create \
        charged particles (Compton, photoelectric, pair production events) \
        to proceed if the interacting photon has survived Russian Roulette \
        (is "fat").  This saves tremendous amounts of CPU time if you are\
        only interested in photons at the bottom of the accelerator.  However,\
        if you require charged particle data, then you must "recreate" some \
        charged particles using charged particle splitting.  To do this, you\
        must select a CM in which the charged particles are to be split. \
        Usually, the CM should be the one modeling the flattening filter. \
        Currently, only FLATFILT supports e-/e+ splitting, so only those \
        components modeled using FLATFILT appear in the list of CMs for\
        splitting.  Once you have selected the CM, then you must select\
        the horizontal plane in the CM that splitting is to be done at. \
        Planes are defined by the layer boundaries within the CM, and once\
        you have defined the geometry of your CM, these planes (and their Z\
        values) become accessible in the "e-/e+ splitting plane no." menu. \
        Usually, the splitting plane selected is the one that defines the \
        bottom of the flattening filter (ie the last one in the CM). \
        Fat charged particles crossing the splitting plane will be split \
        NBRSPL times (and have weight 1/NBRSPL).  You have the option to \
        redistribute these split charged particles in a radially-symmetric \
        manner, which can improve statistics in a radially-symmetric beam.

Charged particle splitting on its own will not result in a large \
        enough improvement in e-/e+ statistics, so we have also implemented\
        a Russian Roulette plane.  This is a horizontal plane which should be\
        placed somewhere above the splitting plane (but it is not restricted\
        to being at a layer boundary).  Above the Russian Roulette plane,\
        standard DBS is carried out.  Below this plane, however, DBS is \
        modified to allow the generation of low-weight charged particles.\
        Compton, photoelectric, and pair production events are not restricted \
        to fat photons, and the subroutine do_smart_compton, which only \
        generates one fat electron from a split Compton interaction, is not\
        used. Placement of the Russian Roulette plane relative to the splitting\
        plane depends on the energy of the beam and the geometry of the \
        flattening filter being modeled, but its exact position is not\
        critical.  In a simulated 6 MV SL25 beam, we found that placing the\
        Russian Roulette plane 0.16 cm above the splitting plane optimized \
        e-/e+ efficiency.

With charged particle splitting, DBS can result in dose efficiencies up to\
        6 times greater than with SBS, 23 times greater than with with UBS,\
        and 160 times greater than with no splitting.
      }
    } elseif {$iopt==3} {
      set text {
Directional Source Biasing (DSB):

Directional source biasing can be used to increase the efficiency of isotropically \
radiating photon sources modelled using ISOURC=3.

The user selects a splitting field radius (FS), defined at an source-to-surface distance \
(SSD) encompassing the treatment field.  Primary photons directed into this field are \
split a user-selected number of times (NBRSPL).  If there is radial symmetry at the top \
of the treatment head, then further CPU time can be saved by splitting and radially redistributing \
primary photons upon entering the CM where radial symmetry ends (splitcm_dsb), thus reducing \
the number of primary photons that must be tracked above this CM.  The number of times that photons \
are split on entering splitcm_dsb is determined by the minimum linear distance between these split, radially
redistributed photons (dsb_delta). \
This input is used to divide the splitting field into radial bins, where each bin has an associated splitting \
number for primary photons directed into it.

If you are interested in electron contamination, then you must use electron (e-/e+) splitting.  Electron \
splitting uses the same algorithm as in directional bremsstrahlung splitting (DBS).  Inputs for electron splitting \
are similar to directional bremsstrahlung splitting in a MV photon beam with the exceptions that: 1) in general, secondary electron \
energies for isotropically radiating sources (e.g. Co-60) are lower than for MV photon beams, so the \
e-/e+ splitting plane and Russian Roulette plane may be closer to the SSD; 2) electron splitting may occur \
in a region of the treatment head that does not have radial symmetry, in which case you should not radially \
redistribute split e-/e+.

Note that directional bremsstrahlung splitting must be turned on to use DSB.  All DSB input parameters are \
shared with directional bremsstrahlung splitting with the exception of the additional \
inputs, splitcm_dsb and dsb_delta.  Thus, if you are \
selecting the parameters for DSB and open the window for inputting directional bremsstrahlung splitting \
you will see that the parameters there match their equivalent values in the DSB input window.

DSB has been shown to increase the efficiency of Co-60 dose calculations by a factor of up to ~400. \
Efficiency is maximized for a photon splitting number = ~20,000 and does not vary significantly for splitting \
numbers higher than this.  Also, efficiency shows little variation with the min. linear distance between \
split, radially-redistributed photons, and a value of 1.5 cm is recommended should you opt to split/radially \
redistribute photons.

For more information about DSB, see the BEAMnrc Manual.
  }
  }
    help_dialog $w.help "Help" $text info 0 OK
}

proc help_special_N { w } {
    set text {
The IWATCH option is set to\
	output for every discrete interaction as well as for every\
	electron/photon step, starting at the history entered.  Until then,\
	normal output is used.
}
    help_dialog $w.help "Help" $text info 0 OK
}

proc help_scoring { w } {
    set text {
For each of the scoring planes, \
	indicate which CM the plane corresponds to and whether the\
	zones are defined as square or annular. \
	Then define the scoring zones for each plane by indicating the\
	number of zones desired for this plane and clicking on the\
	">>" button to set the outer radius/half-width of each zone\
	(in increasing order, please).
}
    help_dialog $w.help "Help" $text info 0 OK
}

proc help_score_contaminant { w } {
    set text {
Identify selected particles as contaminants\
	if they enter this CM.  The dose from these particles is then scored\
	as contaminant dose in all dose zones.
}
    help_dialog $w.help "Help" $text info 0 OK
}
proc help_contaminant_type { w } {
    set text {
Select the contaminant type (photons or\
	charged particles).  Al particles of this type are identified\
	as contaminants when they enter the component module\
	identified above.
}
    help_dialog $w.help "Help" $text info 0 OK
}
proc help_exclusive { w } {
    set text {
Enter the number of exclusive bit filters you\
	wish to use.  Click ">>" to continue on to define them.  See the manual\
	for further information on LATCH and the filters.}
    help_dialog $w.help "Help" $text info 0 OK
}
proc help_inclusive { w } {
    set text {
Enter the number of inclusive bit filters you\
	wish to use.  Click ">>" to continue on to define them.  See the manual\
	for further information on LATCH and the filters.
}
    help_dialog $w.help "Help" $text info 0 OK
}

proc help_title { w } {
    set text {
Enter the title of the CM in this space, up\
	to a maximum of 80 characters.}
    help_dialog $w.help "Help" $text info 0 OK
}

proc help_rmax { w } {
    set text {
Enter the boundary of the CM here.  For\
	a CM with square boundaries, this means to enter the\
	half-width of the maximum boundary.  For a CM with\
	radial symmetry. it means the maximum radius of the CM.  \
	For more information, please refer to the main help button\
	for this CM.
}
    help_dialog $w.help "Help" $text info 0 OK
}

proc help_zmin { w } {
    set text {
This is the distance from the front of the first non-air material\
	in the CM to Z=0, the front of the accelerator.  \
	This is not quite the same as the distance from the\
	front of the CM which may include an air gap.
}
    help_dialog $w.help "Help" $text info 0 OK
}

proc help_zback { w } {
    set text {
This is the distance from the back of the last non-air material\
	in the CM to Z=0, the front of the accelerator.  \
	This is not quite the same as the distance from the\
	front of the CM which may include an air gap.}
    help_dialog $w.help "Help" $text info 0 OK
}

proc help_force_bdd { w } {
    set text {
If a particle passes through the\
	starting CM to the stopping CM number, it is\
	forced to interact there for the start number of interactions\
	first interactions. The WEIGHT of this photon is reduced\
	and the remaining WEIGHT is carried by another photon\
	which will be transported.
}
    help_dialog $w.help "Help" $text info 0 OK
}

proc help_ifluor { w } {
    set text {
This option is rarely used as it requires\
	a lot of CPU time and has a negligible effect on the results at\
	high energies.  The effective Z is used in the regions marked,\
	inclusive.
}
    help_dialog $w.help "Help" $text info 0 OK
}

proc help_source9 { w } {
    set text {
Source 9 is a discrete field from a point source at Z=0.\
	The field is given as probabilities for each (x,y) pair.\
	Note that the probabilities need not be normalized; BEAM\
	does that automatically.
}
    help_dialog $w.help "Help" $text info 0 OK
}

proc help_sameaslayer { w } {
    set text {
With this option, you can designate the properties\
	of a layer to be the same as one previously defined.  Select the\
	layer then click 'Apply'.  Be aware that the parameter values\
	for the current layer will be permanently changed.}
    help_dialog $w.help "Help" $text info 0 OK
}

proc help_ecut { w } {
    set text {
The cutoff energy for electrons in this region.  \
	If the energy of an electron drops below this value, \
	the electron is no longer tracked and its energy is\
	deposited in the current region.  The default value for \
	this parameter is the global electron cutoff, set in the main\
	parameters.  Note that if the value set here is less than the\
	global value, it is automatically set equal to the global\
	value.  This parameter is an important time-saving device.}
    help_dialog $w.help "Help" $text info 0 OK
}

proc help_pcut { w } {
    set text {
The cutoff energy for photons in this region.  \
	If the energy of a photon drops below this value, \
	the photon is no longer tracked and its energy is\
	deposited in the current region.  The default value for \
	this parameter is the global photon cutoff, set in the main\
	parameters.}
    help_dialog $w.help "Help" $text info 0 OK
}

proc help_dose { w } {
    set text {
Indicate whether you want dose to be scored in this CM\
	and if so, which dose component to associate it with.  Set\
	this value to zero if you do not want to score dose in this\
	region of the CM.}
    help_dialog $w.help "Help" $text info 0 OK
}

proc help_latch { w } {
    set text {
Set the bit to associate with this region, \
	for use with the bit filters applied when dose\
	components are used.}
    help_dialog $w.help "Help" $text info 0 OK
}

proc help_material { w } {
    set text {
Set the medium for this region.  The option menu contains all of the\
	materials available in the PEGS4 cross-sectional data file\
	that you selected on loading the accelerator.  If these materials\
	are not what you wanted, select the 'Change PEGS4 file' option\
	on the main window File menu and select a new set of materials.}
    help_dialog $w.help "Help" $text info 0 OK
}

proc help_cons3r_RR { w } {
    set text {
Set this parameter to -1 if you want to turn off\
	range rejection in this region.  Set it to 0 if you want to use\
	the global value.}
    help_dialog $w.help "Help" $text info 0 OK
}

proc help_esave { w } {
    set text {
ESAVE sets the maximum energy that a particle can have\
	for range rejection to be considered.  It is used\
	to minimize errors due to the assumption that any bremsstrahlung\
	photons created when energy is deposited in a region do not leave\
	that region.  It's default value\
	is ESAVE_GLOBAL, set in the main inputs.}
    help_dialog $w.help "Help" $text info 0 OK
}


